react-waterfall-render

react-waterfall-render

Renders nested React components with asynchronous cached loading.

Useful for GraphQL clients (e.g. graphql-react) and server side rendering.

Installation

To install with npm, run:

npm install react-waterfall-render

Use the WaterfallRenderContext in React components to declare asynchronous cached loading, and use the function waterfallRender to server side render your React app in a fully loaded state.

Requirements

• Node.js: ^12.22.0 || ^14.17.0 || >= 16.0.0
• Browsers: > 0.5%, not OperaMini all, not IE > 0, not dead

API

• function waterfallRender
• member WaterfallRenderContext
• type DeclareLoading
• type ReactNode

function waterfallRender

Resolves a React node rendered with all data loaded within cached.

It repeatedly renders the React node and awaits any loading cache promises declared within (using the declare loading function via WaterfallRenderContext), until no further loading is declared; implying all data has loaded and is rendered from cache.

If server side rendering, afterwards the cache should be serialized for hydration on the client prior to the initial client side render.

Intended for use in a Node.js environment for server side rendering, but could potentially be used for preloading components in modern browser environments that support async functions, etc.

Parameter	Type	Description
reactNode	ReactNode	React virtual DOM node.
render	Function	Synchronous React render function, e.g. ReactDOMServer.renderToStaticMarkup (faster), or ReactDOMServer.renderToString (slower).

Returns: Promise<*> — Resolves the final render result, typically a HTML string.

Examples

How to import.

import waterfallRender from "react-waterfall-render/waterfallRender.mjs";

How to server side render a React app in Node.js.

import ReactDOMServer from "react-dom/server.js";
import waterfallRender from "react-waterfall-render/waterfallRender.mjs";
import App from "./components/App.mjs";

waterfallRender(<App />, ReactDOMServer.renderToStaticMarkup).then((html) => {
  // Do something with the HTML string…
});

---

member WaterfallRenderContext

React context object for making the declare loading function available within components when rendering with waterfallRender.

Type: object

Property	Type	Description
Provider	Function	React context provider component.
Consumer	Function	React context consumer component.

Examples

How to import.

import WaterfallRenderContext from "react-waterfall-render/WaterfallRenderContext.mjs";

Use within a component with the useContext React hook.

import React from "react";
import WaterfallRenderContext from "react-waterfall-render/WaterfallRenderContext.mjs";

const declareLoading = React.useContext(WaterfallRenderContext);

---

type DeclareLoading

Declares loading cache promises to waterfallRender. Available within React components via WaterfallRenderContext.

Type: Function

Parameter	Type	Description
promises	…Promise<*>	Promises that resolve once loading data has been cached. The values resolved don’t matter. Multiple arguments can be used, similar to how Array.push works.

Examples

Loading data in a React component within a server and client side rendered app.

import React from "react";
import WaterfallRenderContext from "react-waterfall-render/WaterfallRenderContext.mjs";
import useUserProfileData from "../hooks/useUserProfileData.mjs";
import UserProfile from "./UserProfile.mjs";

export default function UserPage({ userId }) {
  const declareLoading = React.useContext(WaterfallRenderContext);
  const { load, loading, cache } = useUserProfileData(userId);

  // For this example, assume loading errors are cached.
  if (cache) return <UserProfile data={cache} />;

  if (!loading) {
    const userDataPromise = load();

    // Only present when the app is server side rendered using the function
    // `waterfallRender`.
    if (declareLoading) {
      declareLoading(userDataPromise);

      // This render is on the server and will be discarded anyway for a
      // re-render once the declared loading promises resolve, so it’s
      // slightly more efficient to render nothing; particularly if the
      // loading state is expensive to render.
      return null;
    }
  }

  return "Loading…";
}

---

type ReactNode

A React virtual DOM node; anything that can be rendered.

Type: undefined | null | boolean | number | string | React.Element | Array<ReactNode>

Changelog

3.0.0

Major

• Updated Node.js support to ^12.22.0 || ^14.17.0 || >= 16.0.0.
• Updated dev dependencies, some of which require newer Node.js versions than previously supported.
• Public modules are now individually listed in the package files and exports fields.
• Removed ./package from the package exports field; the full package.json filename must be used in a require path.
• Removed the package main index module; deep imports must be used.
• Shortened public module deep import paths, removing the /public/.
• The API is now ESM in .mjs files instead of CJS in .js files, accessible via import but not require.
• Now uses React.createElement instead of the the new React JSX runtime.

Patch

• Also run GitHub Actions CI with Node.js v17.
• Simplified package scripts.
• Avoid named imports from react and react-dom as they’re not proper Node.js ESM.
• Removed conditionality on the Node.js global process.env.NODE_ENV.
• Error messages are now more detailed.
• Reorganized the test file structure.
• Renamed imports in the test index module.
• Test the bundle sizes for public modules individually.
• Use a new assertBundleSize function to assert module bundle size in tests:
  • Failure message contains details about the bundle size and how much the limit was exceeded.
  • Errors when the surplus is greater than 25% of the limit, suggesting the limit should be reduced.
  • Resolves the minified bundle and its gzipped size for debugging in tests.
• Configured Prettier option singleQuote to the default, false.
• Documentation tweaks.
• Amended the changelog entry for v2.0.0.